QVAC-18735 feat[api]: add POST /v1/audio/translations to qvac serve OpenAI adapter#2031
Merged
Merged
Conversation
- e2e.bats: cover POST /v1/audio/translations with WHISPER_EN_TINY_Q8_0 alias, assert it rejects transcription-only and chat aliases, and that DELETE unloads both whisper aliases. - serve/config.ts: flatten whisperConfig into top-level modelConfig keys for whispercpp-audio-translation (whisper loadModel expects flat fields, not nested whisperConfig); force translate=true and warn otherwise. - config.test.ts: assert flat translate/language/n_threads and no whisperConfig key; cover top-level translate=false override. - docs/serve-openai.md: clarify src accepts SDK model constants and show the flat config shape.
The virtual `whispercpp-audio-translation` type previously required the
explicit `{ type, src }` shape, but `src` is passed to the SDK verbatim
so an SDK constant name like `WHISPER_EN_TINY_Q8_0` failed with
MODEL_NOT_FOUND. Allow constant entries to carry an optional `type`
override instead, so `{ "model": "WHISPER_EN_TINY_Q8_0", "type":
"whispercpp-audio-translation" }` resolves the constant via the
registry and then runs through the virtual-type mapping
(`whispercpp-transcription` + audio-translation + translate=true).
- serve/config.ts: ConstantModelEntry gains optional `type`;
resolveModelConstant routes the override through
resolveExplicitServeModel. Explicit `{ type, src }` branch is
unchanged (src is still a literal modelSrc).
- config.test.ts: exports + covers natural-addon resolution, the
whisper → audio-translation override, and unknown-constant errors.
- e2e.bats: test-whisper-translate now uses the model+type shape.
- docs/serve-openai.md: recommend the model+type shorthand; note that
explicit src is for non-registry weights only.
1de73d4 to
3141840
Compare
opaninakuffo
approved these changes
May 14, 2026
opaninakuffo
left a comment
Contributor
There was a problem hiding this comment.
Adds /v1/audio/translations, the whispercpp-audio-translation virtual type (flatten + forced translate), startup/docs/package files, and solid unit + BATS coverage. Mirrors the transcriptions handler cleanly and gates on audio-translation nicely.
Contributor
Tier-based Approval Status |
simon-iribarren
approved these changes
May 14, 2026
simon-iribarren
left a comment
Contributor
There was a problem hiding this comment.
Approve. Verified locally: build ✓, typecheck ✓, 243/243 tests pass. CI green on all technical gates.
Three things worth surfacing:
routes/translations.tsis a ~95% duplicate ofroutes/transcriptions.ts. Only ~12 effective lines differ (endpoint category,languagepolicy, log labels, error code), and validation order is already drifting between the two siblings. Worth factoring a sharedhandleWhisperAudio(req, res, ctx, { requiredCategory, opLabel, errorCode, languagePolicy })helper before the third Whisper variant lands.transcribeOverridewas added to the publicRouteContextinterface but onlytranslations.tsconsumes it.transcriptions.tsstill callssdkTranscribedirectly. Wrong test seam — either flip both routes to read fromctx, or passsdkTranscribeinto a handler factory and drop theRouteContextfield.whisperConfignested→flat flattening is asymmetric.config.ts::resolveExplicitServeModelflattens only for the virtualwhispercpp-audio-translationtype. Plainwhispercpp-transcriptionentries with nestedwhisperConfigpass through unchanged, even though the newserve-openai.mdtells transcription users to use flat keys. Silent footgun — either flatten symmetrically or document the asymmetry.
Smaller nits:
response_formatallowlist is case-sensitive; OpenAI clients send lowercase, but the divergence will catch someone.console.warnin the config parser — prefer the structured logger.- No client-disconnect propagation (same wart as transcriptions).
- No
changelog/0.3.0/api.mdupdate in this PR — easy to add.
NamelsKing
approved these changes
May 14, 2026
Contributor
Author
|
/review |
Contributor
Author
|
/review |
Proletter
pushed a commit
that referenced
this pull request
May 24, 2026
…penAI adapter (#2031) * feat[api]: add POST /v1/audio/translations to qvac serve OpenAI adapter * test[api]: add e2e + flatten whisper translate config - e2e.bats: cover POST /v1/audio/translations with WHISPER_EN_TINY_Q8_0 alias, assert it rejects transcription-only and chat aliases, and that DELETE unloads both whisper aliases. - serve/config.ts: flatten whisperConfig into top-level modelConfig keys for whispercpp-audio-translation (whisper loadModel expects flat fields, not nested whisperConfig); force translate=true and warn otherwise. - config.test.ts: assert flat translate/language/n_threads and no whisperConfig key; cover top-level translate=false override. - docs/serve-openai.md: clarify src accepts SDK model constants and show the flat config shape. * fix[api]: allow type override on constant serve.models entries The virtual `whispercpp-audio-translation` type previously required the explicit `{ type, src }` shape, but `src` is passed to the SDK verbatim so an SDK constant name like `WHISPER_EN_TINY_Q8_0` failed with MODEL_NOT_FOUND. Allow constant entries to carry an optional `type` override instead, so `{ "model": "WHISPER_EN_TINY_Q8_0", "type": "whispercpp-audio-translation" }` resolves the constant via the registry and then runs through the virtual-type mapping (`whispercpp-transcription` + audio-translation + translate=true). - serve/config.ts: ConstantModelEntry gains optional `type`; resolveModelConstant routes the override through resolveExplicitServeModel. Explicit `{ type, src }` branch is unchanged (src is still a literal modelSrc). - config.test.ts: exports + covers natural-addon resolution, the whisper → audio-translation override, and unknown-constant errors. - e2e.bats: test-whisper-translate now uses the model+type shape. - docs/serve-openai.md: recommend the model+type shorthand; note that explicit src is for non-registry weights only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 What problem does this PR solve?
qvac serve openaihad no OpenAI-compatible translations endpoint, so consumers that hitPOST /v1/audio/translations(Whisper translate-to-English task) had to fall back to a separate transcribe + text-translate pipeline.serve.modelshad no way to declare a Whisper alias whose endpoint category wasaudio-translation, since the only Whisper type waswhispercpp-transcription.📝 How does it solve it?
POST /v1/audio/translationsto the OpenAI HTTP adapter. Route gates onendpointCategory === 'audio-translation', rejectslanguage(OpenAI translations are English-only), and supportsjson(default) /textresponse formats.serve.modelstypewhispercpp-audio-translation. The CLI resolves it to the real enginewhispercpp-transcriptionand forcestranslate: trueat parse time (warns if the operator settranslate: false). NestedwhisperConfig: { ... }is flattened into the top-levelmodelConfigso it matches what@qvac/sdkloadModelexpects.serve.modelsentry with an optionaltypeoverride, so the recommended config keeps using the same"model": "<SDK_CONSTANT>"shape as every other entry:packages/cli/docs/serve-openai.md, README pointer, andpackage.jsonfilesnow includesdocs/**/*.mdso the doc ships with the published package.🧪 How was it tested?
npm test— addsconfig.test.ts(constant +typeoverride path, virtual-type flattening, translate-true enforcement) andtranslations.test.ts(validation branches: missing fields,languagerejection, non-translation alias gate, unsupported formats, json/text responses).npm run test:bats—cli.batssmoke cases mirroring the transcriptions set.npm run test:e2e—e2e.batsregisterstest-whisper-translateviamodel + typeoverride, hits/v1/audio/translationsfor bothjsonandtext, asserts rejection of a transcription-only alias and of a chat alias, and verifies DELETE unloads both whisper aliases.WHISPER_EN_TINY_Q8_0.🔌 API Changes
New endpoint —
POST /v1/audio/translations:curl -s http://127.0.0.1:11434/v1/audio/translations \ -F model=whisper-translate \ -F file=@./sample.wav \ -F response_format=json # => { "text": "..." } (always English)New
serve.modelsshape — Whisper translation alias via constant +typeoverride:{ "serve": { "models": { "whisper-transcribe": { "model": "WHISPER_EN_TINY_Q8_0", "preload": true }, "whisper-translate": { "model": "WHISPER_EN_TINY_Q8_0", "type": "whispercpp-audio-translation", "preload": true } } } }The explicit
{ "type": "whispercpp-audio-translation", "src": "<weights>" }form is still accepted for non-registry weights (literal URL / path /registry://…);srcis passed to the SDK verbatim and is not resolved against SDK model constants.Ticket
QVAC-18735